package DBD::Yahoo;

use strict;
use vars qw($VERSION $REVISION);
use vars qw($err $errstr $state $drh);

use DBI;
use DBD::Yahoo::dr;
use DBD::Yahoo::db;
use DBD::Yahoo::st;

$VERSION = '0.01';
$err     = 0;
$errstr  = "";
$state   = "";
$drh     = undef;

sub driver
{
  return $drh if $drh;
  my ($class, $attr) = @_;
  my %stuff = (
    'Name'        => 'Yahoo',
    'Version'     => $VERSION,
    'Attribution' => 'DBD::Yahoo - Yen-Ming Lee <leeym@leeym.com>',
    'Err'         => \$err,
    'Errstr'      => \$errstr,
    'State'       => \$state,
    'AutoCommit' => 1,
  );
  $drh = DBI::_new_drh($class . "::dr", \%stuff);
}

sub CLONE { undef $drh; }

sub DESTROY { 1 }

1;

__END__

=head1 NAME

DBD::Yahoo - Treat Yahoo! as a datasource for DBI

=head1 SYNOPSIS

  my $appid = "YahooTaiwanHackday20070209";
  my %opts  = ("Count" => 3);
  my $dbh   = DBI->connect("dbi:Yahoo:", $appid, undef, \%opts);
  my $sth   = $dbh->prepare("SELECT * FROM yahoo WHERE Doc = ? LIMIT 4, 5");
  $sth->execute($q);

=head1 DESCRIPTION

DBD::Yahoo allows you to use Yahoo! as a datasource; Yahoo! can be
queried using SQL SELECT statements, and iterated over using
standard DBI conventions.

=head1 BASIC USAGE

For the most part, use C<DBD::Yahoo> like you use any other DBD,
except instead of going through the trouble of building and installing
(or buying!) database software, and employing a DBA to manage your
data, you can take advantage of Yahoo!'s ability to do this for you.
Think of it as outsourcing your DBA, if you like.

=head2 Connection Information

The connection string should look like: C<dbi:Yahoo:> (DBI requires
the trailing C<:>).

Your Yahoo! AppId should be specified in the username portion (the
password is currently ignored; do whatever you want with it, but be
warned that I might put that field to use some day):

  my $dbh = DBI->connect("dbi:Yahoo:", "my key", undef, \%opts);

In addition to the standard DBI options, the fourth argument to
connect can also include the following C<DBD::Yahoo> specific
options, the full details of each of which can be found in
L<Yahoo::Search>.

=head2 Supported SQL Syntax and Random Notes Thereon

The only supported SQL statement type is the I<SELECT> statement.
Since there is no real "table" involved, I've created a hypothetical
table, called I<yahoo>; this table has several queryable fields: I<Doc>,
I<Image>, I<Video>, I<News>, I<Local>, I<Terms>, I<Spell> and I<Related>.
The available columns are currently dictated by the data available
from the underlying transport, which is the Yahoo! API (see
L<http://developer.yahoo.com/>), as implemented by Jeffrey Friedl's
C<Yahoo::Search> module.

The basic SQL syntax supported looks like:

  SELECT @fields FROM yahoo WHERE Doc = '$query'

There is also an optional LIMIT clause, the syntax of which is similar
to that of MySQL's LIMIT clause; it takes a pair: offset from 0,
number of results.  In practice, Yahoo! returns 10 results at a time
by default, so specifying a higher LIMIT clause at the beginning might
make sense for some queries.

The list of available fields in the I<yahoo> table includes:
I<I>, I<i>, I<Url>, I<ClickUrl>, I<Title>, I<Summary>, I<CacheUrl>,
I<CacheSize>, I<ModTimestamp>, I<Width>, I<Height>, I<ThumbUrl>,
I<ThumbWidth>, I<ThumbHeight>, I<HostUrl>, I<Copyright>, I<Publisher>,
I<Restrictions>, I<Type>, I<Bytes>, I<Channels>, I<Seconds>, I<Duration>,
I<Streaming>, I<SourceName>, I<SourceUrl>, I<Language>, I<PublishTime>,
I<PublishWhen>, I<Address>, I<City>, I<State>, I<Phone>, I<Miles>,
I<Kilometers>, I<Rating>, I<MapUrl>, I<BusinessUrl>, I<BusinessClickUrl>,
I<AllMapUrl>, I<Term>. Please see C<Yahoo::Search::Result> for details.

=head1 SEE ALSO

Yahoo::Search(3), Yahoo::Search::Result(3), DBD::Google(3).

http://developer.yahoo.com/

=head1 AUTHOR

Yen-Ming Lee, E<lt>leeym@leeym.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2007 by Yen-Ming Lee.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.

=cut
